<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
	<meta name="description" content="description"/>
	<meta name="keywords" content="keywords"/>
  <meta name="author" content="Kyle Yetter"/>
	<link rel="stylesheet" type="text/css" href="stylesheets/article.css" media="screen"/>
  <link rel="stylesheet" type="text/css" href="stylesheets/ANTLR3.css" media="screen"/>
  <link rel="stylesheet" type="text/css" href="stylesheets/ruby.css" media="screen"/>

	<title>ANTLR For Ruby: Parsers</title>
</head>

<body>
<div class="left">
	<div class="header">
		<h2><span>ANTLR for Ruby</span></h2>
		<h1>Parsers</h1>
	</div>
	<div class="annotation">
		<div class="author">by <a href="mailto:kcy5b@yahoo.com">Kyle Yetter</a></div>
    <div class="timestamp">updated Sunday, August 04, 2013 at 09:59PM EDT</div>
	</div>
	<div class="content">
<h1 id="section-1">Parser Code and Class Structure</h1>
<p>For a <code>combined</code> or pure <code>parser</code> grammar named <code>Language</code>, <code>antlr4ruby</code> will generate a parser class. In other <span class="caps">ANTLR</span> targets, the generated class is named <code>LanguageParser</code>. However, this ruby implementation will generate a top level module named <code>Language</code>, which serves as a general name-space for the various entities required by the code. The actual parser class is simply named <code>Parser</code>, so the full name of the generated parser will be <code>Language::Parser</code>. Consider this combined grammar:</p>
<div class="code-frame">
  <table class="ANTLR3" id="AddingMachine">
  <tr class="code_line" id="AddingMachine-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">AddingMachine</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">options&nbsp;{</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="id">language</span><span class="ws">&nbsp;</span><span class="o">=</span><span class="ws">&nbsp;</span><span class="id">Ruby</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="k">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="kd">expression</span><span class="ws">&nbsp;</span><span class="ret">returns</span><span class="arg_action">[&nbsp;value&nbsp;]</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="nl">a</span><span class="o">=</span><a href="#AddingMachine-11"><span class="n">NUMBER</span></a><span class="ws">&nbsp;</span><span class="s2">&#39;+&#39;</span><span class="ws">&nbsp;</span><span class="nl">b</span><span class="o">=</span><a href="#AddingMachine-11"><span class="n">NUMBER</span></a><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$value</span><span class="kt">&nbsp;=&nbsp;</span><span class="si">$a</span><span class="kt">.text.to_i&nbsp;+&nbsp;</span><span class="si">$b</span><span class="kt">.text.to_i&nbsp;}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-9">
    <td class="line_number odd"><pre>09</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="nl">a</span><span class="o">=</span><a href="#AddingMachine-11"><span class="n">NUMBER</span></a><span class="ws">&nbsp;</span><span class="s2">&#39;-&#39;</span><span class="ws">&nbsp;</span><span class="nl">b</span><span class="o">=</span><a href="#AddingMachine-11"><span class="n">NUMBER</span></a><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$value</span><span class="kt">&nbsp;=&nbsp;</span><span class="si">$a</span><span class="kt">.text.to_i&nbsp;-&nbsp;</span><span class="si">$b</span><span class="kt">.to_i&nbsp;}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-10">
    <td class="line_number even"><pre>10</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-11">
    <td class="line_number odd"><pre>11</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-12">
    <td class="line_number even"><pre>12</pre></td>
    <td class="code"><pre><span class="kd">NUMBER</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="p">(</span><span class="ws">&nbsp;</span><span class="s2">&#39;0&#39;</span><span class="ws">&nbsp;</span><span class="o">..</span><span class="ws">&nbsp;</span><span class="s2">&#39;9&#39;</span><span class="ws">&nbsp;</span><span class="p">)</span><span class="o">+</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-13">
    <td class="line_number odd"><pre>13</pre></td>
    <td class="code"><pre><span class="kd">SPACE</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;&nbsp;&#39;</span><span class="o">+</span><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$channel</span><span class="kt">&nbsp;=&nbsp;HIDDEN&nbsp;}</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
<p>An abbreviated form of the output generated by <code>antlr4ruby AddingMachine.g</code> is shown below:</p>
<div class="code-frame">
  <table class="ruby" id="ruby70001862308500">
  <tr class="code_line" id="ruby70001862308500-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="c1">#&nbsp;edited&nbsp;out&nbsp;run-time&nbsp;library&nbsp;require&nbsp;procedure</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">module</span><span class="tx">&nbsp;</span><span class="nn">AddingMachine</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="c1">#&nbsp;TokenData&nbsp;defines&nbsp;all&nbsp;of&nbsp;the&nbsp;token&nbsp;type&nbsp;integer&nbsp;values</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="c1">#&nbsp;as&nbsp;constants,&nbsp;which&nbsp;will&nbsp;be&nbsp;included&nbsp;in&nbsp;all&nbsp;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="c1">#&nbsp;ANTLR-generated&nbsp;recognizers.</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="nb">const_defined?</span><span class="p">(</span><span class="ss">:TokenData</span><span class="p">)</span><span class="tx">&nbsp;</span><span class="ow">or</span><span class="tx">&nbsp;</span><span class="no">TokenData</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">ANTLR3</span><span class="p">:</span><span class="ss">:TokenScheme</span><span class="o">.</span><span class="n">new</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-9">
    <td class="line_number odd"><pre>09</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="k">module</span><span class="tx">&nbsp;</span><span class="nn">TokenData</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-10">
    <td class="line_number even"><pre>10</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;define&nbsp;the&nbsp;token&nbsp;constants</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-11">
    <td class="line_number odd"><pre>11</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="n">define_tokens</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="ss">:NUMBER</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="o">&gt;</span><span class="tx">&nbsp;</span><span class="mi">4</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="ss">:EOF</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="o">&gt;</span><span class="tx">&nbsp;</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="ss">:SPACE</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="o">&gt;</span><span class="tx">&nbsp;</span><span class="mi">5</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="ss">:T__7</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="o">&gt;</span><span class="tx">&nbsp;</span><span class="mi">7</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="ss">:T__6</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="o">&gt;</span><span class="tx">&nbsp;</span><span class="mi">6</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-12">
    <td class="line_number even"><pre>12</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-13">
    <td class="line_number odd"><pre>13</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;register&nbsp;the&nbsp;proper&nbsp;human-readable&nbsp;name&nbsp;or&nbsp;literal&nbsp;value</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-14">
    <td class="line_number even"><pre>14</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;for&nbsp;each&nbsp;token&nbsp;type</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-15">
    <td class="line_number odd"><pre>15</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-16">
    <td class="line_number even"><pre>16</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;this&nbsp;is&nbsp;necessary&nbsp;because&nbsp;anonymous&nbsp;tokens,&nbsp;which&nbsp;are</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-17">
    <td class="line_number odd"><pre>17</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;created&nbsp;from&nbsp;literal&nbsp;values&nbsp;in&nbsp;the&nbsp;grammar,&nbsp;do&nbsp;not</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-18">
    <td class="line_number even"><pre>18</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;have&nbsp;descriptive&nbsp;names</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-19">
    <td class="line_number odd"><pre>19</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="n">register_names</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">NUMBER</span><span class="s2">&quot;</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">SPACE</span><span class="s2">&quot;</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">&#39;+&#39;</span><span class="s2">&quot;</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">&#39;-&#39;</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-20">
    <td class="line_number even"><pre>20</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="k">end</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-21">
    <td class="line_number odd"><pre>21</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-22">
    <td class="line_number even"><pre>22</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-23">
    <td class="line_number odd"><pre>23</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="k">class</span><span class="tx">&nbsp;</span><span class="nc">Parser</span><span class="tx">&nbsp;</span><span class="o">&lt;</span><span class="tx">&nbsp;</span><span class="ss">ANTLR3</span><span class="p">:</span><span class="ss">:Parser</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-24">
    <td class="line_number even"><pre>24</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="vi">@grammar_home</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="no">AddingMachine</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-25">
    <td class="line_number odd"><pre>25</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-26">
    <td class="line_number even"><pre>26</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="no">RULE_METHODS</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="o">[</span><span class="tx">&nbsp;</span><span class="ss">:expression</span><span class="tx">&nbsp;</span><span class="o">]</span><span class="o">.</span><span class="n">freeze</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-27">
    <td class="line_number odd"><pre>27</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-28">
    <td class="line_number even"><pre>28</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="kp">include</span><span class="tx">&nbsp;</span><span class="no">TokenData</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-29">
    <td class="line_number odd"><pre>29</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-30">
    <td class="line_number even"><pre>30</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="n">generated_using</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">./AddingMachine.g</span><span class="s2">&quot;</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">3.2.1-SNAPSHOT&nbsp;Dec&nbsp;18,&nbsp;2009&nbsp;04:29:28</span><span class="s2">&quot;</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">1.6.3</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-31">
    <td class="line_number odd"><pre>31</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-32">
    <td class="line_number even"><pre>32</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="k">def</span><span class="tx">&nbsp;</span><span class="nf">initialize</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">input</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="n">options</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="p">{</span><span class="p">}</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-33">
    <td class="line_number odd"><pre>33</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="k">super</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">input</span><span class="p">,</span><span class="tx">&nbsp;</span><span class="n">options</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-34">
    <td class="line_number even"><pre>34</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="k">end</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-35">
    <td class="line_number odd"><pre>35</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-36">
    <td class="line_number even"><pre>36</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;Rules&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-&nbsp;-</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-37">
    <td class="line_number odd"><pre>37</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-38">
    <td class="line_number even"><pre>38</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;parser&nbsp;rule&nbsp;expression</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-39">
    <td class="line_number odd"><pre>39</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-40">
    <td class="line_number even"><pre>40</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;(in&nbsp;./AddingMachine.g)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-41">
    <td class="line_number odd"><pre>41</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;7:1:&nbsp;expression&nbsp;returns&nbsp;[&nbsp;value&nbsp;]&nbsp;:&nbsp;(a=&nbsp;NUMBER&nbsp;&#39;+&#39;&nbsp;b=&nbsp;NUMBER&nbsp;|&nbsp;a=&nbsp;NUMBER&nbsp;&#39;-&#39;&nbsp;b=&nbsp;NUMBER&nbsp;);</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-42">
    <td class="line_number even"><pre>42</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-43">
    <td class="line_number odd"><pre>43</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="k">def</span><span class="tx">&nbsp;</span><span class="nf">expression</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-44">
    <td class="line_number even"><pre>44</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;edited&nbsp;50+&nbsp;lines&nbsp;of&nbsp;recognition&nbsp;logic</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-45">
    <td class="line_number odd"><pre>45</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="k">end</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-46">
    <td class="line_number even"><pre>46</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-47">
    <td class="line_number odd"><pre>47</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;edited&nbsp;out&nbsp;various&nbsp;other&nbsp;support&nbsp;code</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-48">
    <td class="line_number even"><pre>48</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="k">end</span><span class="tx">&nbsp;</span><span class="c1">#&nbsp;class&nbsp;Parser&nbsp;&lt;&nbsp;ANTLR3::Parser</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-49">
    <td class="line_number odd"><pre>49</pre></td>
    <td class="code"><pre><span class="k">end</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001862308500-50">
    <td class="line_number even"><pre>50</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<p>Thus, the generated code for a parser creates the following named entities:</p>
<ol>
	<li><code>module Language</code> &#8211; where <code>Language</code> is the name of the input grammar</li>
	<li><code>class Language::Parser &lt; ANTLR3::Parser</code> &#8211; the parser implementation</li>
	<li><code>module Language::TokenData</code> &#8211; an <code>ANTLR3::TokenScheme</code> (subclass of <code>Module</code>), which is used to define token types and a token class</li>
	<li><code>class Language::TokenData::Token &lt; ANTLR3::CommonToken</code> &#8211; not apparent in the code above, this class is dynamically created along with <code>Language::TokenData</code></li>
</ol>
<h1 id="section-2">Instantiating Parsers</h1>
<h2>Providing a Token Stream</h2>
<p>A parser must be provided with a stream of tokens to recognize.</p>
<div class="code-frame">
  <table class="ruby" id="ruby70001867429760">
  <tr class="code_line" id="ruby70001867429760-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Lexer</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">1&nbsp;+&nbsp;1</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867429760-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="n">tokens</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">ANTLR3</span><span class="p">:</span><span class="ss">:CommonTokenStream</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867429760-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="n">parser</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">tokens</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867429760-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<h2>Providing a Lexer or ANTLR3::TokenSource Object</h2>
<div class="code-frame">
  <table class="ruby" id="ruby70001867463100">
  <tr class="code_line" id="ruby70001867463100-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Lexer</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">1&nbsp;+&nbsp;1</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867463100-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="n">parser</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867463100-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<h2>Providing an Input String or File</h2>
<p>If the parser class is able to automatically figure out which lexer class to use to tokenize the input, the four-step instantiation process can be reduced to a single step as demonstrated below.</p>
<div class="code-frame">
  <table class="ruby" id="ruby70001867486940">
  <tr class="code_line" id="ruby70001867486940-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="n">parser</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">1&nbsp;+&nbsp;1</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867486940-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867486940-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="n">parser</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867486940-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="nb">open</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s1">&#39;sums.txt&#39;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx">&nbsp;</span><span class="p">{</span><span class="tx">&nbsp;</span><span class="o">|</span><span class="tx">&nbsp;</span><span class="n">f</span><span class="tx">&nbsp;</span><span class="o">|</span><span class="tx">&nbsp;</span><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">f</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx">&nbsp;</span><span class="p">}</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867486940-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<p>This can only happen in these circumstances:</p>
<ul>
	<li>the parser is generated from a <strong>combined</strong> lexer/parser grammar</li>
	<li>the parser class itself has an instance variable named <code>@associated_lexer</code> which has been assigned to a lexer class to use for automatic input tokenization</li>
</ul>
<p>Since <code>AddingMachine.g</code> is a combined grammar, the sample code above works without any extra work. To demonstrate the second scenario, consider rewriting <code>AddingMachine</code> as a pure parser grammar. While this example is somewhat contrived and impractical, say you would like to define two different lexers &#8212; one for decimal numbers and one for hexadecimal numbers. So you write two different lexers:</p>
<div class="code-frame">
  <table class="ANTLR3" id="Decimal">
  <tr class="code_line" id="Decimal-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">lexer</span><span class="ws">&nbsp;</span><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">Decimal</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">options&nbsp;{</span><span class="ws">&nbsp;</span><span class="id">language</span><span class="ws">&nbsp;</span><span class="o">=</span><span class="ws">&nbsp;</span><span class="id">Ruby</span><span class="p">;</span><span class="ws">&nbsp;</span><span class="k">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="kt">@</span><span class="kt">token</span><span class="kt">::</span><span class="kt">members</span><span class="ws">&nbsp;</span><span class="kt">{</span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;def&nbsp;value</span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;text.to_i</span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;end</span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-9">
    <td class="line_number odd"><pre>09</pre></td>
    <td class="code"><pre><span class="kt">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-10">
    <td class="line_number even"><pre>10</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-11">
    <td class="line_number odd"><pre>11</pre></td>
    <td class="code"><pre><span class="kd">NUMBER</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="p">(</span><span class="ws">&nbsp;</span><span class="s2">&#39;0&#39;</span><span class="ws">&nbsp;</span><span class="o">..</span><span class="ws">&nbsp;</span><span class="s2">&#39;9&#39;</span><span class="ws">&nbsp;</span><span class="p">)</span><span class="o">+</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-12">
    <td class="line_number even"><pre>12</pre></td>
    <td class="code"><pre><span class="kd">PLUS</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;+&#39;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-13">
    <td class="line_number odd"><pre>13</pre></td>
    <td class="code"><pre><span class="kd">MINUS</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;-&#39;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Decimal-14">
    <td class="line_number even"><pre>14</pre></td>
    <td class="code"><pre><span class="kd">SPACE</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;&nbsp;&#39;</span><span class="o">+</span><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$channel</span><span class="kt">&nbsp;=&nbsp;HIDDEN&nbsp;}</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
<div class="code-frame">
  <table class="ANTLR3" id="Hexadecimal">
  <tr class="code_line" id="Hexadecimal-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">lexer</span><span class="ws">&nbsp;</span><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">Hexadecimal</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">options&nbsp;{</span><span class="ws">&nbsp;&nbsp;</span><span class="id">language</span><span class="ws">&nbsp;</span><span class="o">=</span><span class="ws">&nbsp;</span><span class="id">Ruby</span><span class="p">;</span><span class="ws">&nbsp;</span><span class="k">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="kt">@</span><span class="kt">token</span><span class="kt">::</span><span class="kt">members</span><span class="ws">&nbsp;</span><span class="kt">{</span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;def&nbsp;value</span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;text.to_i(&nbsp;16&nbsp;)</span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;end</span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-9">
    <td class="line_number odd"><pre>09</pre></td>
    <td class="code"><pre><span class="kt">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-10">
    <td class="line_number even"><pre>10</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-11">
    <td class="line_number odd"><pre>11</pre></td>
    <td class="code"><pre><span class="kd">NUMBER</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="p">(</span><span class="ws">&nbsp;</span><span class="s2">&#39;0&#39;</span><span class="ws">&nbsp;</span><span class="o">..</span><span class="ws">&nbsp;</span><span class="s2">&#39;9&#39;</span><span class="ws">&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="s2">&#39;a&#39;</span><span class="ws">&nbsp;</span><span class="o">..</span><span class="ws">&nbsp;</span><span class="s2">&#39;f&#39;</span><span class="ws">&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="s2">&#39;A&#39;</span><span class="ws">&nbsp;</span><span class="o">..</span><span class="ws">&nbsp;</span><span class="s2">&#39;F&#39;</span><span class="ws">&nbsp;</span><span class="p">)</span><span class="o">+</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-12">
    <td class="line_number even"><pre>12</pre></td>
    <td class="code"><pre><span class="kd">PLUS</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;+&#39;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-13">
    <td class="line_number odd"><pre>13</pre></td>
    <td class="code"><pre><span class="kd">MINUS</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;-&#39;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Hexadecimal-14">
    <td class="line_number even"><pre>14</pre></td>
    <td class="code"><pre><span class="kd">SPACE</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="s2">&#39;&nbsp;&#39;</span><span class="o">+</span><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$channel</span><span class="kt">&nbsp;=&nbsp;HIDDEN&nbsp;}</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
<p>So say you imagine the most common usage scenario for <code>AddingMachine</code> is using decimal numbers. If you still want to use automatic input tokenization, you would write <code>AddingMachine</code> like this:</p>
<div class="code-frame">
  <table class="ANTLR3" id="AddingMachine">
  <tr class="code_line" id="AddingMachine-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">parser</span><span class="ws">&nbsp;</span><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">AddingMachine</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">options&nbsp;{</span><span class="ws">&nbsp;&nbsp;</span><span class="id">language</span><span class="ws">&nbsp;</span><span class="o">=</span><span class="ws">&nbsp;</span><span class="id">Ruby</span><span class="p">;</span><span class="ws">&nbsp;</span><span class="k">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="kt">@</span><span class="kt">members</span><span class="ws">&nbsp;</span><span class="kt">{</span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;require&nbsp;&#39;Decimal&#39;</span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="kt">&nbsp;&nbsp;@associated_lexer&nbsp;=&nbsp;Decimal::Lexer</span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre><span class="kt">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-9">
    <td class="line_number odd"><pre>09</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-10">
    <td class="line_number even"><pre>10</pre></td>
    <td class="code"><pre><span class="kd">expression</span><span class="ws">&nbsp;</span><span class="ret">returns</span><span class="arg_action">[&nbsp;value&nbsp;]</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-11">
    <td class="line_number odd"><pre>11</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="nl">a</span><span class="o">=</span><span class="gr">NUMBER</span><span class="ws">&nbsp;</span><span class="gr">PLUS</span><span class="ws">&nbsp;&nbsp;</span><span class="nl">b</span><span class="o">=</span><span class="gr">NUMBER</span><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$value</span><span class="kt">&nbsp;=&nbsp;</span><span class="si">$a</span><span class="kt">.value&nbsp;+&nbsp;</span><span class="si">$b</span><span class="kt">.value&nbsp;}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-12">
    <td class="line_number even"><pre>12</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="nl">a</span><span class="o">=</span><span class="gr">NUMBER</span><span class="ws">&nbsp;</span><span class="gr">MINUS</span><span class="ws">&nbsp;</span><span class="nl">b</span><span class="o">=</span><span class="gr">NUMBER</span><span class="ws">&nbsp;</span><span class="kt">{&nbsp;</span><span class="si">$value</span><span class="kt">&nbsp;=&nbsp;</span><span class="si">$a</span><span class="kt">.value&nbsp;-&nbsp;</span><span class="si">$b</span><span class="kt">.value&nbsp;}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AddingMachine-13">
    <td class="line_number odd"><pre>13</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
<p>After generating code for all three grammars, the following code will work correctly:</p>
<div class="code-frame">
  <table class="ruby" id="ruby70001867856740">
  <tr class="code_line" id="ruby70001867856740-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="nb">require</span><span class="tx">&nbsp;</span><span class="s1">&#39;AddingMachine&#39;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">100&nbsp;-&nbsp;10</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="o">.</span><span class="n">expression</span><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;=&gt;&nbsp;90</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="nb">require</span><span class="tx">&nbsp;</span><span class="s1">&#39;Hexadecimal&#39;</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="o">=</span><span class="tx">&nbsp;</span><span class="ss">Hexadecimal</span><span class="p">:</span><span class="ss">:Lexer</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="s2">&quot;</span><span class="s2">FF&nbsp;-&nbsp;01</span><span class="s2">&quot;</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-7">
    <td class="line_number odd"><pre>07</pre></td>
    <td class="code"><pre><span class="ss">AddingMachine</span><span class="p">:</span><span class="ss">:Parser</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">lexer</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="o">.</span><span class="n">expression</span><span class="tx">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="c1">#&nbsp;=&gt;&nbsp;254</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867856740-8">
    <td class="line_number even"><pre>08</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<h1 id="section-3">Parser Rules</h1>
<p>Each parser rule is implemented as a method of the parser class. Thus, rule <code>statement</code> in grammar <code>Language.g</code> will be implemented as method <code>Language#statement</code>.</p>
<h2>Rule Method Arguments</h2>
<p><span class="caps">ANTLR</span> does allow rules to be specified with arguments. For example:</p>
<div class="code-frame">
  <table class="ANTLR3" id="Args">
  <tr class="code_line" id="Args-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">Args</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Args-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Args-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="kd">statement</span><span class="arg_action">[&nbsp;include_loops&nbsp;]</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Args-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="sempred">{&nbsp;include_loops&nbsp;}?</span><span class="ws">&nbsp;</span><span class="p">(</span><span class="ws">&nbsp;</span><span class="gr">loop</span><span class="ws">&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="gr">conditional</span><span class="ws">&nbsp;</span><span class="p">)</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Args-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="gr">conditional</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Args-6">
    <td class="line_number even"><pre>06</pre></td>
    <td class="code"><pre><span class="ws">&nbsp;&nbsp;</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
<p>will produce code that contains</p>
<div class="code-frame">
  <table class="ruby" id="ruby70001867950800">
  <tr class="code_line" id="ruby70001867950800-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">def</span><span class="tx">&nbsp;</span><span class="nf">statement</span><span class="p">(</span><span class="tx">&nbsp;</span><span class="n">include_loops</span><span class="tx">&nbsp;</span><span class="p">)</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867950800-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="tx">&nbsp;&nbsp;</span><span class="c1">#&nbsp;a&nbsp;whole&nbsp;bunch&nbsp;of&nbsp;recognition&nbsp;code&nbsp;...</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867950800-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">end</span><span class="tx"></span></pre></td>
  </tr>
  <tr class="code_line" id="ruby70001867950800-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<p>Rule argument specification is more limited than ruby&#8217;s argument specification syntax. Unfortunately, this is beyond my control as a target developer. Rule argument specification is mostly controlled by ANTLR&#8217;s core syntax and the <span class="caps">ANTLR</span> tool&#8217;s semantics, which is somewhat skewed in favor of Java&#8217;s semantics. Thus,</p>
<ul>
	<li>arguments may not have default values (as in &#8220;<code>include_loops = false</code>&#8221;)</li>
	<li>you cannot specify &#8220;splat&#8221; arguments (as in &#8220;<code>*args</code>&#8221;)</li>
</ul>
<h2>Rule Method Visibility</h2>
<p>By default, all rule methods are <code>public</code>. However, <span class="caps">ANTLR</span> permits specifying rule visibility with modifiers <code>public</code>, <code>protected</code>, or <code>private</code>. The generated source code will honor these modifiers, setting the rule method&#8217;s visibility.</p>
<div class="code-frame">
  <table class="ANTLR3" id="Whatevs">
  <tr class="code_line" id="Whatevs-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">Whatevs</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Whatevs-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Whatevs-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">public</span><span class="ws">&nbsp;</span><span class="kd">a</span><span class="ws">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="gr">ID</span><span class="ws">&nbsp;</span><span class="s2">&#39;=&#39;</span><span class="ws">&nbsp;</span><a href="#Whatevs-3"><span class="n">b</span></a><span class="ws">&nbsp;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Whatevs-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="k">protected</span><span class="ws">&nbsp;</span><span class="kd">b</span><span class="ws">&nbsp;&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><a href="#Whatevs-4"><span class="n">c</span></a><span class="ws">&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="gr">ID</span><span class="ws">&nbsp;</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="Whatevs-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre><span class="k">private</span><span class="ws">&nbsp;</span><span class="kd">c</span><span class="ws">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="p">:</span><span class="ws">&nbsp;</span><span class="gr">NUM</span><span class="ws">&nbsp;</span><span class="p">|</span><span class="ws">&nbsp;</span><span class="gr">STR</span><span class="ws">&nbsp;</span><span class="p">;</span></pre></td>
  </tr>
</table>

</div>
	</div>
</div>

<div class="nav">
	<div class="logo"><span></span></div>

	<ul>
		<li><a href="#section-1">Parser Code and Class Structure</a></li>
		<li><a href="#section-2">Instantiating Parsers</a></li>
		<li><a href="#section-3">Parser Rules</a></li>
	</ul>
</div>

<div class="right">
	<div class="round">		
		<div class="roundtl"><span></span></div>
		<div class="roundtr"><span></span></div>
		<div class="clearer"><span></span></div>
	</div>

	<div class="subnav">
		<h1>Contents</h1>
		<ul>
      <li><a href="./index.html">Home</a></li>
      <li><a href="./GettingStarted.html">Getting Started</a></li>
      <li><a href="./Lexers.html">Lexers</a></li>
  		<li class="current">Parsers</li>
      <li><a href="./Tokens.html">Tokens</a></li>
      <li><a href="./ActionBlocks.html">Action Blocks</a></li>
      <li><a href="./Scopes.html">Scopes</a></li>
      <li class="todo"><a href="./TreeParsers.html">Tree Parsers</a></li>
      <li class="todo"><a href="./ASTs.html">Abstract Syntax Trees</a></li>
      <li><a href="./BuiltInDrivers.html">Built-In Drivers</a></li>
      <li class="todo"><a href="./TemplateMode.html">Template Mode</a></li>
      <li class="todo"><a href="./DebugMode.html">Debug Mode</a></li>
      <li class="todo"><a href="./ProfileMode.html">Profile Mode</a></li>
      <li class="todo"><a href="./Extras.html">Extras</a></li>
		</ul>
		
    <h1>Project Links</h1>
		<ul>
      <li><a href="http://github.com/ohboyohboyohboy/antlr3">GitHub</a></li>
      <li><a href="http://rubygems.org/gems/antlr3">Ruby Gems</a></li>
      <li><a href="http://rubyforge.org/projects/antlr3">Rubyforge</a></li>
      <li><a href="http://github.com/ohboyohboyohboy/antlr3/issues">Bug Reports</a></li>
		</ul>
		
    <h1>External Links</h1>
		<ul>
      <li><a href="http://www.antlr.org">ANTLR.org</a></li>
      <li><a href="http://www.antlr.org/wiki/display/ANTLR3/ANTLR+Cheat+Sheet">ANTLR Cheat Sheet</a></li>
      <li><a href="http://www.antlr.org/wiki/display/ANTLR3/ANTLR+v3+documentation">ANTLR Documentation</a></li>
      <li><a href="http://www.antlr.org/grammar/list">Sample Grammar Exchange</a></li>
		</ul>
	</div>

	<div class="round">
		<div class="roundbl"><span></span></div>
		<div class="roundbr"><span></span></div>
		<span class="clearer"></span>
	</div>
</div>

<div class="footer">
	
  &copy; 2010 <a href="mailto:kcy5b@yahoo.com">Kyle Yetter</a>. Valid <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a> &amp; <a href="http://validator.w3.org/check?uri=referer">XHTML</a>. <a href="http://templates.arcsin.se">Website template</a> by <a href="http://arcsin.se">Arcsin</a>

</div>
</body>

</html>